该功能特性从 v2.5
版本开始提供。该命令目前仅支持 HTTP
接口开发, GRPC
部分请参考 gen pb
命令。未来会考虑 HTTP
及 GRPC
统一使用该命令生成控制器及 SDK
源代码。
基本介绍
解决痛点
在开发项目的时候,往往需要先根据业务需求和场景设计 API
接口, 使用 proto
或者 golang struct
来设计 API
的输入和输出,随后再创建与 API
相对应的控制器实现,最后也有可能会提供 SDK
(同为 Golang
语言条件下)供内/外部服务调用。在开发过程中会遇到以下痛点:
- 重复性的代码工作较繁琐。在
API
中创建输入输出定义文件后还需要在控制器目录下创建对应的文件、创建对应的控制器初始化代码、从API
代码中反复拷贝各个输入输出结构名称,在这过程重复性的操作比较繁琐。 - API与控制器之间的关联没有可靠规范约束。除了
API
有一定的命名约束外,控制器的创建和方法命名并没有约束,灵活度较高,API
的结构名称与控制器方法名称难以约束对应,当接口越来越多时会有一定维护成本。 - 团队开发多人协作时代码文件冲突概率大。多人开发协作都往一个文件执行变更时,出现文件冲突的概率就会变大,团队协作开发中处理这种文件冲突的精力开销毫无意义。
- 缺少API的HTTP SDK自动生成工具。当开发完
API
后,往往需要立即给内部或者外部调用,缺少便捷的SDK
生成,需要手动来维护这部分SDK
代码,那么对于调用端来说成本非常高。
命令特性
- 规范了
API
定义与控制器文件命名、控制器实现方法命名。 - 规范了
API
定义与控制器代码之间的关联关系,便于快速定位API
实现。 - 根据
API
定义自动生成控制器接口、控制器初始化文件及代码、接口初始化代码。 - 根据
API
定义自动生成易于使用的HTTP SDK
代码。该功能可配置,默认关闭。 - 支持
File Watch
自动化生成模式:当某个API
结构定义文件发生变化时,自动增量化更新对应的控制器、SDK
代码。
前置约定
重要的规范🔥
该命令的目的之一是规范化 api
代码的编写,那么我们应该有一些重要的规范需要了解(否则生成不了代码哦):
api
层的接口定义文件路径需要满足/api/模块/版本/定义文件.go
,例如:/api/user/v1/user.go
、/api/user/v1/user_delete.go
、etc.- 这里的 模块 指的是
API
的模块划分,我们可以将API
按照不同的 业务属性 进行拆分方便聚合维护。你也可以将模块认为是具体的业务资源。 - 这里的 版本 通常使用
v1
/v2
..这样的形式来定义,用以API
兼容性的版本控制。当相同的API
出现兼容性更新时,需要通过不同版本号来区分。默认使用v1
来管理第一个版本。 - 这里的 定义文件 指的是
API
的输入输出定义文件,通常每个API
需要单独定义一个go
文件来独立维护。当然也支持将多个API
放到一个go
文件中统一维护。
- 这里的 模块 指的是
api
定义的结构体名称需要满足操作+Req
及操作+Res
的命名方式。例如:GetOneReq/GetOneRes
、GetListReq/GetListRes
、DeleteReq/DeleteRes
、etc.- 这里的操作是当前
API
模块的操作名称,通常对应CURD
是:Create
、Update
、GetList/GetOne
、Delete
。
- 这里的操作是当前
以下是项目工程模板中的 Hello
接口示例:
建议性的命名
我们对一些常用的接口定义做了一些建议性的命名,供大家参考:
操作名称 | 建议命名 | 备注 |
---|---|---|
查询列表 | GetListReq/Res | 通常是从数据库中分页查询数据记录 |
查询详情 | GetOneReq/Res | 通常接口需要传递主键条件,从数据库中查询记录详情 |
创建资源 | CreateReq/Res | 通常是往数据表中插入一条或多条数据记录 |
修改资源 | UpdateReq/Res | 通常是按照一定条件修改数据表中的一条或多条数据记录 |
删除资源 | DeleteReq/Res | 通常是按照一定条件删除数据表中 的一条或多条数据记录 |
命令使用
该命令通过分析给定的 api
接口定义目录下的代码,自动生成对应的控制器/ SDK Go
代码文件。
手动模式
如果是手动执行命令行,直接在项目根目录下执行 gf gen ctrl
即可,她将完整扫描 api
接口定义目录,并生成对应代码。
$ gf gen ctrl -h
USAGE
gf gen ctrl [OPTION]
OPTION
-s, --srcFolder source folder path to be parsed. default: api
-d, --dstFolder destination folder path storing automatically generated go files. default: internal/controller
-w, --watchFile used in file watcher, it re-generates go files only if given file is under srcFolder
-k, --sdkPath also generate SDK go files for api definitions to specified directory
-v, --sdkStdVersion use standard version prefix for generated sdk request path
-n, --sdkNoV1 do not add version suffix for interface module name if version is v1
-h, --help more information about this command
EXAMPLE
gf gen ctrl
如果使用框架推荐的项目工程脚手架,并且系统安装了 make
工具,也可以使用 make ctrl
快捷指令。
参数说明:
名称 | 必须 | 默认值 | 含义 |
---|---|---|---|
srcFolder | 否 | api | 指向 api 接口定义文件目录地址 |
dstFolder | 否 | internal/controller | 指向生成的控制器文件存放目录 |
watchFile | 否 | 用在IDE的文件监控中,用于根据当文件发生变化时自动执行生成操作 | |
sdkPath | 否 | 如果需要生成 HTTP SDK ,该参数用于指定生成的SDK代码目录存放路径 | |
sdkStdVersion | 否 | 生成的 HTTP SDK 是否使用标准的版本管理。标准的版本管理将自动根据 API 版本增加请求的路由前缀。例如 v1 版本的API将会自动增加 /api/v1 的请求路由前缀。 | |
sdksdkNoV1 | 否 | 生成的 HTTP SDK 中,当接口为 v1 版本时,接口模块名称是否不带 V1 后缀。 |
自动模式(推荐)
如果您是使用的 GolandIDE
,那么可以使用我们提供的配置文件: watchers.xml 自动监听代码文件修改时自动生成接口文件。使用方式,如下图:
使用示例
自动生成的接口定义文件
自动生成的控制器代码文件
自动生成的 HTTP SDK
代码文件
常见问题
为什么每一个 api
接口生成一个 controller
文件而不是合并到一个 controller
文件中
当然,针对小型项目或者个人简单项目、一个 api
模块只有几个接口的项目而言,管理的方式并不会成为什么问题,可以根据个人喜好维护代码文件即可。我们这里以较复杂的业务项目,或者企业级项目,在一个 api
模块的接口比较多的场景来展开描述一下。
- 首先,开发
api
接口时,查找api
接口实现更加清晰,而不是在一个动则上千行的代码文件中查找。